URL Rewriting #872

marmoure · 2023-01-03T14:19:28Z

Closes #200 .
This PR uses @wolfgangmm #227 for the URL Rewriting and all the fixes in that Pr.
It removes outdated parts, rename all xql to xq.

This open source contribution to the documentation project was commissioned by the Office of the Historian, U.S. Department of State, https://history.state.gov/.

joewiz · 2023-01-17T18:25:49Z

Thank you, @marmoure and @adamretter.

With the stated goal of #200 being a thoroughly updated article that is approachable and presents the key information that users need to know about the URL Rewriting facility (a "major job", as Erik characterized it), I'd suggest that more revision is necessary here. Wolfgang's draft revised introduction is a good start, but the body of the article needs to be reviewed to meet the stated goals of #200. As a starting point, I would suggest reading the relevant sections from the eXist book (pp. 194-207), since it comprehensively describes the URL rewriting facility. Make a note of what's covered there - for example, permissions considerations - and be sure all information is addressed here and introduced coherently. As Erik recommended, "postpone stuff about servlets and MVC patterns and all stuff you don't need for the basic understanding to sections at the end." The article should address the typical user looking to exert full control over their URLs and tell them what they need to know to do so.

Also, please be sure the CI passes.

yamahito · 2023-01-31T13:29:46Z

@joewiz I've spent some time reworking the article, restructuring in some places, adding examples, and aiming for a more concise wording. How does it look?

src/main/xar-resources/data/urlrewrite/urlrewrite.xml

line-o · 2023-01-31T17:03:31Z

@yamahito much clearer now 👍🏼

joewiz · 2023-02-06T22:29:25Z

src/main/xar-resources/data/urlrewrite/urlrewrite.xml

+<?xml-model href="http://docbook.org/xml/5.0/rng/docbook.rng" schematypens="http://relaxng.org/ns/structure/1.0"?><?xml-model href="http://docbook.org/xml/5.0/rng/docbook.rng" type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron"?><article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
  <info>
    <title>URL Rewriting</title>
    <date>2Q19</date>


According to the Author Reference, this should be updated to February 2023 or 1Q23.

Yes; will fix that.

joewiz · 2023-02-06T22:35:09Z

src/main/xar-resources/data/urlrewrite/urlrewrite.xml

+      </orderedlist>
+    <sect2 xml:id="eg1">
+      <title>Example I: A Simple Implementation</title>
+      <para>Consider  the document you are currently reading; a direct URL pointing to the source data might be <code>/exist/apps/doc/data/urlrewrite.xml</code>.  But accessing this URI  would only show a user the raw XML: instead users should get a properly formatted HTML version of the text, accessible through a simple URL like <code>/exist/apps/doc/urlrewrite</code>.</para>


I think the direct source URL to the source XML for this article would be /exist/rest/db/apps/doc/data/urlrewrite.xml.

I will reword this, since the URLs do not really point to this exact document (which is at /exist/apps/doc/data/urlrewrite/urlrewrite.xml - I think bringing the rest interface into it muddies the waters even further). I considered changing all of the URLs to match the actual docbook article, but I think the important thing is that they are consistent.

joewiz · 2023-02-06T22:54:45Z

src/main/xar-resources/data/urlrewrite/urlrewrite.xml

-        </term>
+      </orderedlist>
+    <sect2 xml:id="eg1">
+      <title>Example I: A Simple Implementation</title>


The next example is "Example 2", so perhaps best to stick with Arabic numerals -> "Example 1".

I have ~~added Example C~~ fixed.

joewiz · 2023-02-06T22:55:54Z

src/main/xar-resources/data/urlrewrite/listings/listing-1.txt

+declare variable $exist:root external;
+
+<dispatch xmlns="http://exist.sourceforge.net/NS/exist">
+    <forward url="{$exist:controller}/modules/transform.xql">


The text refers to this XQuery as transform.xq - i.e., without the l.

joewiz · 2023-02-06T22:56:08Z

src/main/xar-resources/data/urlrewrite/listings/listing-2.txt

+<dispatch xmlns="http://exist.sourceforge.net/NS/exist">
+    <forward url="data/{$exist:resource}.xml"/>
+    <view>
+        <forward url="{$exist:controller}/modules/transform.xql"/>


The text refers to this XQuery as transform.xq - i.e., without the l.

joewiz · 2023-02-06T22:58:54Z

src/main/xar-resources/data/urlrewrite/urlrewrite.xml

+      <para><literal>controller.xq</literal> is invoked for all URL paths targeting the collection in which it resides. It has access to a number of <xref linkend="variables"/> pre-filled with details about the request, including <literal>$exist:resource</literal>, containing the name of the resource (without path components) the request tries to access; also the <literal>$exist:controller</literal> variable which points to the collection the <literal>controller.xq</literal> is located in.</para>
+      <para>For example, one may want to direct all requests to <literal>/exist/apps/doc/{resource}</literal> to an XQuery, <literal>transform.xq</literal>, which is responsible for converting the XML content into HTML:</para>
+      <programlisting language="xquery" xlink:href="listings/listing-1.txt"/>
+      <para>This example controller returns a simple <tag>dispatch</tag> fragment which will be passed back to the URL rewriting framework. The <tag>forward</tag> element instructs the framework to call the URL <literal>modules/transform.xq</literal> relative to the collection in which the controller resides. It adds a request parameter, named <literal>doc</literal>, which translates the requested resource into an actual document path to be transformed.</para>


Consider adding another sentence to the end of this paragraph:

The receiving query could access this parameter using request:get-parameter("doc", ()) in order to retrieve the requested article.

joewiz · 2023-02-06T23:02:41Z

src/main/xar-resources/data/urlrewrite/urlrewrite.xml

+      <para><literal>controller.xq</literal> is invoked for all URL paths targeting the collection in which it resides. It has access to a number of <xref linkend="variables"/> pre-filled with details about the request, including <literal>$exist:resource</literal>, containing the name of the resource (without path components) the request tries to access; also the <literal>$exist:controller</literal> variable which points to the collection the <literal>controller.xq</literal> is located in.</para>
+      <para>For example, one may want to direct all requests to <literal>/exist/apps/doc/{resource}</literal> to an XQuery, <literal>transform.xq</literal>, which is responsible for converting the XML content into HTML:</para>
+      <programlisting language="xquery" xlink:href="listings/listing-1.txt"/>
+      <para>This example controller returns a simple <tag>dispatch</tag> fragment which will be passed back to the URL rewriting framework. The <tag>forward</tag> element instructs the framework to call the URL <literal>modules/transform.xq</literal> relative to the collection in which the controller resides. It adds a request parameter, named <literal>doc</literal>, which translates the requested resource into an actual document path to be transformed.</para>


I'm not sure it's totally accurate to say that the request parameter named doc "translates the requested resource into an actual document path". Instead, doc contains the name of the resource sans path components (e.g., urlrewrite) plus the file extension of the actual document stored in the database (e.g., urlrewrite.xml).

yamahito · 2023-02-09T09:51:06Z

@joewiz I've attempted to address your feedback points. Thanks!

src/main/xar-resources/data/urlrewrite/urlrewrite.xml

- `xref/@linkend` already correctly handles cross references using the title of the resource, but `link` can also use `@linkend` where internal links are desirable with different labels. - Refactored for best practice push XSLT paradigm.

- Built on existing work by Wolfgang and others - removed extra verbal padding for more concise document - Re-ordered some of the more complex topics to the end of the document - Re-factored headings for easier navigation from sidebar (e.g. controller XML model) and better internal linking - Reviewed the eXist O'Reilly book content to ensure documentation parity - Added some examples

@xml

- missing @xml:id on `sect2` - replace `tag` within `link` with `literal`

- corrected query names to `.xq` from `xql` in examples - Updated date - renumbered examples for consistency - Reworded Example 1

adamretter · 2023-03-19T18:07:53Z

@joewiz I have fixed the date and cleaned up the commit history. This should be ready for you to merge now if you are happy to do so.

joewiz · 2023-03-19T18:11:20Z

@adamretter Would you please pull in my evolvedbinary#1, so that this PR incorporates that review?

adamretter · 2023-03-19T18:26:38Z

@joewiz Sorry, I wasn't aware of your evolvedbinary#1.
I think it''s best not to send PRs to our fork please.

I just took a look at that PR and there seems to be merge conflicts. Can I suggest that this gets merged first, and then you could reopen your PR against this repo.

joewiz · 2023-03-20T02:48:57Z

@adamretter Ok, that'll work.

joewiz

@yamahito Thanks, this is a great article!

marmoure changed the title ~~URL Rewriting intro~~ URL Rewriting Jan 16, 2023

line-o reviewed Jan 31, 2023

View reviewed changes

src/main/xar-resources/data/urlrewrite/urlrewrite.xml Outdated Show resolved Hide resolved

joewiz reviewed Feb 6, 2023

View reviewed changes

joewiz reviewed Mar 18, 2023

View reviewed changes

src/main/xar-resources/data/urlrewrite/urlrewrite.xml Outdated Show resolved Hide resolved

wolfgangmm and others added 16 commits March 19, 2023 19:06

[refactor] Add gentle introduction to URL rewriting.

af1a67a

[bugfix] remove outdated parts

44a5348

[bugfix] Remove the outdated warning

16a78a9

[bugfix] add missing para

d7ac70f

[bugfix] xql file should be xq now

0592fd9

[refactor] Quick touch up

9c793be

[bugfix] Improves handling of internal link

1a12df3

- `xref/@linkend` already correctly handles cross references using the title of the resource, but `link` can also use `@linkend` where internal links are desirable with different labels. - Refactored for best practice push XSLT paradigm.

[bugfix] Added missing xml:id to URLRewrite

8634f47

[bugfix] Corrected URLRewrite for failing mvn tests

af4ca96

- missing @xml:id on `sect2` - replace `tag` within `link` with `literal`

[rewrite] Clarified URLRewrite language; per PR review by @line-o

ccc2f80

[refactor] Incorporated PR feedback

d99f5b9

- corrected query names to `.xq` from `xql` in examples - Updated date - renumbered examples for consistency - Reworded Example 1

[bugfix] Fix minor typo

ed5a255

[bugfix] Fix grammar issues

f4bd928

[refactor] Minor tidy up and some consistency improvements

77e516b

[bugfix] Correct the year, to address PR review from @joewiz

53ef78e

adamretter force-pushed the url-rewrite branch from 3198f17 to 53ef78e Compare March 19, 2023 18:06

joewiz mentioned this pull request Mar 19, 2023

WIP: Rewrite document on URL rewriting #227

Closed

joewiz approved these changes Mar 20, 2023

View reviewed changes

joewiz merged commit e8f95f7 into eXist-db:master Mar 20, 2023

yamahito deleted the url-rewrite branch March 20, 2023 10:27

This was referenced Dec 19, 2023

[BUG] URL rewrite article validation errors #928

Closed

Also test against Java 17 #905

Closed

Fix ci #929

Merged

Uh oh!

URL Rewriting #872

URL Rewriting #872

Uh oh!

Conversation

marmoure commented Jan 3, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

joewiz commented Jan 17, 2023

Uh oh!

yamahito commented Jan 31, 2023

Uh oh!

Uh oh!

line-o commented Jan 31, 2023

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

joewiz Feb 6, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yamahito commented Feb 9, 2023

Uh oh!

Uh oh!

adamretter commented Mar 19, 2023

Uh oh!

joewiz commented Mar 19, 2023

Uh oh!

adamretter commented Mar 19, 2023

Uh oh!

joewiz commented Mar 20, 2023

Uh oh!

joewiz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

marmoure commented Jan 3, 2023 •

edited

Loading

joewiz Feb 6, 2023 •

edited

Loading